home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / a_utils / _archvrs / amiga / pplib.lzh / PPLib / doc / pplib.doc
Text File  |  1991-11-10  |  21KB  |  621 lines
  1. TABLE OF CONTENTS
  2.  
  3. powerpacker.library/ppAllocCrunchInfo
  4. powerpacker.library/ppCalcChecksum
  5. powerpacker.library/ppCalcPasskey
  6. powerpacker.library/ppCrunchBuffer
  7. powerpacker.library/ppDecrunchBuffer
  8. powerpacker.library/ppDecrypt
  9. powerpacker.library/ppEnterPassword
  10. powerpacker.library/ppErrorMessage
  11. powerpacker.library/ppFreeCrunchInfo
  12. powerpacker.library/ppGetPassword
  13. powerpacker.library/ppLoadData
  14. powerpacker.library/ppWriteDataHeader
  15. powerpacker.library/ppAllocCrunchInfo   powerpacker.library/ppAllocCrunchInfo
  16.  
  17.   NAME  ppAllocCrunchInfo()  (V35)
  18.  
  19.     crunchinfo = ppAllocCrunchInfo (efficiency, speedup, function, userdata);
  20.  
  21.     APTR ppAllocCrunchInfo (ULONG, ULONG, BOOL (*)(), APTR);
  22.     D0                      D0     D1     A0          A1
  23.  
  24.   DESCRIPTION
  25.     Allocate all the necessary memory needed to crunch a buffer. This
  26.     function must be called before using ppCrunchBuffer.  You must pass
  27.     the crunching efficiency and the size of the speedup buffer.
  28.  
  29.     You can pass a callback function to be called during crunching. Use this
  30.     type of function:
  31.  
  32.     BOOL __stdargs myFunction (ULONG lensofar, ULONG crunlen,
  33.                                ULONG totlen, APTR userdata);
  34.  
  35.     If you do not wish to use this feature pass a NULL. The function can be
  36.     used for two things:
  37.  
  38.       o to display the percentage crunched and gain so far.
  39.       o to allow the user to abort crunching.
  40.  
  41.     Your function will be passed four arguments (on the stack, normal C
  42.     conventions):
  43.  
  44.       lensofar - length of part crunched so far.
  45.       crunlen  - crunched length of lensofar.
  46.       totlen   - total length of buffer.
  47.       userdata - the userdata you provided to ppAllocCrunchInfo().
  48.  
  49.     If your function returns a non-zero value the crunching will continue,
  50.     returning zero will abort crunching.
  51.  
  52.     SAS/C users shouldn't forget __saveds if they compiled their program with
  53.     the small data model and wish to use global data in their function.
  54.     If you write your function in assembly please preserve all registers.
  55.  
  56.     Example:
  57.  
  58.     BOOL __stdargs __saveds myfunc (ULONG sofar, ULONG crunlen,
  59.                                     ULONG totlen, APTR userdata)
  60.     {
  61.        struct IntuiMessage *msg;
  62.        UWORD code;
  63.  
  64.        if (sofar) {
  65.           sprintf (buff, "%ld%% crunched. (%ld%% gain)   ",
  66.              (sofar * 100) / totlen, 100 - (100 * crunlen) / sofar);
  67.           PrtMsg (buff, BLACK|AT_START);
  68.           }
  69.        while (msg = (struct IntuiMessage *)GetMsg (win->UserPort)) {
  70.           code = msg->Code;
  71.           ReplyMsg ((struct Message *)msg);
  72.           if (code == 0x3 /* CTRL-C */) return (FALSE);
  73.           }
  74.        return (TRUE);
  75.     }
  76.  
  77.     Finally note that you may scratch the A4 register.  This is made possible
  78.     to help people who wish to use 'userdata' to pass A4 (C data pointer).
  79.  
  80.   INPUTS
  81.     efficiency - the efficiency of the crunching. One of the
  82.                  following (defined in "libraries/ppbase.[hi]"):
  83.                     CRUN_FAST
  84.                     CRUN_MEDIOCRE
  85.                     CRUN_GOOD
  86.                     CRUN_VERYGOOD
  87.                     CRUN_BEST
  88.     speedup    - size of speedup buffer to be used. One of the
  89.                  following (defined in "libraries/ppbase.[hi]"):
  90.                     SPEEDUP_BUFFSMALL  - from 3K (fast) to 33K (best)
  91.                     SPEEDUP_BUFFMEDIUM - from 5K (fast) to 65K (best)
  92.                     SPEEDUP_BUFFLARGE  - from 196K (fast) to 256K (best)
  93.     function   - callback function to be called every so often during
  94.                  crunching. Can be used to display percentage crunched
  95.                  so far and to abort crunching.
  96.     userdata   - anything you wish. Will be passed to your callback function.
  97.  
  98.   RESULT
  99.     crunchinfo - pointer to private crunchinfo structure to be passed to
  100.                  ppCrunchBuffer (use ppFreeCrunchInfo to deallocate).
  101.  
  102.   NOTE
  103.     'crunchinfo' may be re-used to crunch several buffers.
  104.  
  105.   BUGS
  106.     none known
  107.  
  108.   SEE ALSO
  109.     ppFreeCrunchInfo(), ppCrunchBuffer()
  110.  
  111. powerpacker.library/ppCalcChecksum         powerpacker.library/ppCalcChecksum
  112.  
  113.   NAME  ppCalcChecksum()
  114.  
  115.     sum = ppCalcChecksum (string);
  116.  
  117.     ULONG ppCalcChecksum (char *);
  118.     D0:16                 A0
  119.  
  120.   DESCRIPTION
  121.     This function calculates a 16 bit checksum of a given string of
  122.     characters.
  123.  
  124.   INPUTS
  125.     string - pointer to a null terminated character string.
  126.  
  127.   RESULT
  128.     sum - checksum of 'string'.
  129.  
  130.   NOTE
  131.     Function used to check if a password is correct.
  132.     Upper 16 bits of checksum are 0.
  133.  
  134.   BUGS
  135.     none
  136.  
  137.   SEE ALSO
  138.     ppLoadData()
  139.     ppDecrunchBuffer()
  140.     ppDecrypt()
  141.     ppCalcPasskey()
  142.  
  143. powerpacker.library/ppCalcPasskey           powerpacker.library/ppCalcPasskey
  144.  
  145.   NAME  ppCalcPasskey()
  146.  
  147.     key = ppCalcPasskey (password);
  148.  
  149.     ULONG ppCalcPasskey (char *);
  150.     D0                   A0
  151.  
  152.   DESCRIPTION
  153.     This function calculates the 32 bit key associated with the given
  154.     password to encrypt/decrypt crunched files with.
  155.  
  156.   INPUTS
  157.     string - pointer to a null terminated character string.
  158.  
  159.   RESULT
  160.     key - passkey corresponding to the given password.
  161.  
  162.   NOTE
  163.     Function used to decrypt encrypted files.
  164.  
  165.   BUGS
  166.     none
  167.  
  168.   SEE ALSO
  169.     ppDecrunchBuffer()
  170.     ppDecrypt()
  171.     ppCalcChecksum()
  172.  
  173. powerpacker.library/ppCrunchBuffer         powerpacker.library/ppCrunchBuffer
  174.  
  175.   NAME  ppCrunchBuffer()  (V35)
  176.  
  177.     crunchedlen = ppCrunchBuffer (crunchinfo, buffer, len);
  178.  
  179.     ULONG ppCrunchBuffer (APTR, UBYTE *, ULONG);
  180.     D0                    A0    A1       D0
  181.  
  182.   DESCRIPTION
  183.     Crunch the buffer pointed to by 'buffer' and of length (in bytes) 'len'.
  184.     'crunchinfo' must have been previously allocated by ppAllocCrunchInfo().
  185.  
  186.     During crunching your callback function will be called (if you have
  187.     provided one).  See the autodoc for ppAllocCrunchInfo() for more
  188.     information.
  189.  
  190.     The value returned is the length of the crunched buffer.  If you wish to
  191.     save this crunched buffer as a PowerPacker data file you should first
  192.     write the data header using ppWriteDataHeader() en then write the
  193.     crunched buffer.
  194.  
  195.   INPUTS
  196.     crunchinfo  - pointer to private crunchinfo structure returned by
  197.                   ppAllocCrunchInfo().
  198.     buffer      - pointer to buffer to be crunched.
  199.     len         - length of buffer to be crunched.
  200.  
  201.   RESULT
  202.     crunchedlen - length of crunched buffer. In case of an error
  203.                   'crunchedlen' may also equal PP_CRUNCHABORTED or
  204.                   PP_BUFFEROVERFLOW.  Be sure to check this!
  205.  
  206.   NOTE
  207.     Be sure you know what you are doing when you intend to use this function.
  208.     You can easily crash your Amiga by passing wrong arguments or by writing 
  209.     a faulty callback function.
  210.  
  211.   BUGS
  212.     none known
  213.  
  214.   SEE ALSO
  215.     ppAllocCrunchInfo(), ppFreeCrunchInfo()
  216.  
  217. powerpacker.library/ppDecrunchBuffer     powerpacker.library/ppDecrunchBuffer
  218.  
  219.   NAME  ppDecrunchBuffer()
  220.  
  221.     ppDecrunchBuffer (endcrun, decrbuff, effptr, col);
  222.  
  223.     void ppDecrunchBuffer (UBYTE *, UBYTE *, ULONG *, ULONG);
  224.                            A0       A1       A2       D0
  225.  
  226.   DESCRIPTION
  227.     Function to decrunch from one memory location to another. The address of
  228.     the destination can be as close as 8 bytes after the start address of
  229.     the source, so you can decrunch a file with almost no memory overhead.
  230.  
  231.     If you wish to call this function you need to know the format of a
  232.     crunched file:
  233.  
  234.         1 longword identifier           'PP20' or 'PX20'
  235.        [1 word checksum (if 'PX20')     $ssss]
  236.         1 longword efficiency           $eeeeeeee
  237.         X longwords crunched file       $cccccccc,$cccccccc,...
  238.         1 longword decrunch info        'decrlen' << 8 | '8 bits other info'
  239.  
  240.     The following procedure must be followed to decrunch a file:
  241.  
  242.     First you must read 'decrunch info' to find the length of the decrunched
  243.     file, then you must allocate memory to decrunch it in (shift 'decrunch
  244.     info' right 8 bits and add a safety margin (8 bytes) to get the length
  245.     of this memory block).  If the file is encrypted ('PX20') you must call
  246.     ppDecrypt to decrypt the crunched part before calling ppDecrunchBuffer.
  247.  
  248.     So:
  249.     - read identifier.
  250.     - if PX20, read checksum (16 bits, not 32!).
  251.     - read efficiency.
  252.     - read the longword of decrunch info at the end of the file.
  253.     - calculate 'decrlen'.
  254.     - allocate 'decrlen' + 8 (safety margin) bytes.
  255.     - load 'crunched file' and 'decrunch info' at start of allocated memory.
  256.     - if PX20, prompt for a password (check result of ppGetPassword()!).
  257.     - if PX20, calculate the passkey (use ppCalcPasskey).
  258.     - if PX20, call ppDecrypt to decrypt 'crunched file' only.
  259.       (NOT 'decrunch info'!)
  260.     - and finally call ppDecrunchBuffer() with 'endcrun' pointing right after
  261.       'decrunch info', 'decrbuff' pointing 8 bytes after where you loaded the
  262.       file and 'effptr' pointing to the 'efficieny' longword.
  263.  
  264.     If this seems complicated that is probably because it is :-) ppLoadData
  265.     was written to make things simpler and should suffice in most cases.
  266.  
  267.   INPUTS
  268.     endcrun  - pointer just after the last byte of the crunched block.
  269.     decrbuff - pointer to beginning of memory to decrunch to (this must be
  270.                at least 8 bytes behind the start of the crunched file).
  271.     effptr   - pointer to efficiency table.
  272.     col      - decrunching effect (see ppLoadData).
  273.  
  274.   RESULT
  275.     none
  276.  
  277.   NOTE
  278.     This function is used by ppLoadData() and will probably not be used very
  279.     often on its own.
  280.  
  281.   BUGS
  282.     none known
  283.  
  284.   SEE ALSO
  285.     ppLoadData()
  286.     ppDecrypt()
  287.     ppCalcPasskey()
  288.     ppCalcChecksum()
  289.     ppGetPassword()
  290.  
  291. powerpacker.library/ppDecrypt                   powerpacker.library/ppDecrypt
  292.  
  293.   NAME  ppDecrypt()
  294.  
  295.     ppDecrypt (buffer, len, key)
  296.  
  297.     void ppDecrypt (UBYTE *, ULONG, ULONG);
  298.                     A0       D0     D1
  299.  
  300.   DESCRIPTION
  301.     This function will decrypt a memory region with a given passkey. It
  302.     must be called before calling ppDecrunchBuffer() (if the file was
  303.     encrypted).
  304.  
  305.   INPUTS
  306.     buffer - start address of memory region to decrypt (word alligned !).
  307.     len    - length in bytes of memory region to decrypt (rounded up to the
  308.              next multiple of 4).
  309.     key    - key of password as returned by ppCalcPasskey().
  310.  
  311.   RESULT
  312.     none
  313.  
  314.   NOTE
  315.     If you call this function before calling ppDecrunchBuffer make sure you
  316.     decrypt the correct memory region, don't decrypt the last longword !
  317.  
  318.   BUGS
  319.     none
  320.  
  321.   SEE ALSO
  322.     ppDecrunchBuffer()
  323.     ppCalcChecksum()
  324.     ppCalcPasskey()
  325.     ppLoadData()
  326.  
  327. powerpacker.library/ppEnterPassword       powerpacker.library/ppEnterPassword
  328.  
  329.   NAME  ppEnterPassword()  (V35)
  330.  
  331.     bool = ppEnterPassword (screen, buffer);
  332.  
  333.     BOOL ppEnterPassword (struct Screen *, char *);
  334.     D0                    A0               A1
  335.  
  336.   DESCRIPTION
  337.     reqtools.library _MUST_ be available!
  338.  
  339.     Opens a small requester to prompt the user for a password. The password
  340.     will not be visible when typed. Returns when the user has succesfully
  341.     entered a password AND a verification.
  342.  
  343.     When buffer already holds a string on entry, a 'Last' gadget will appear
  344.     in the requester so the user may re-enter his last password without
  345.     retyping it. It is up to you to support this feature. If you do not wish
  346.     to support this make sure buffer holds an empty string (buffer[0] = 0).
  347.  
  348.   INPUTS
  349.     screen - screen where the requester should appear or NULL.
  350.     buffer - buffer to hold the password. Must be at least 17 bytes big!
  351.  
  352.   RESULT
  353.     bool - TRUE if a password was entered (can be found in buffer), FALSE
  354.            if user aborted the requester.
  355.  
  356.   NOTE
  357.     The contents of the buffer will NOT change if the requester is aborted.
  358.  
  359.     Automatically adjusts the requester to the screen's font.
  360.  
  361.     ppEnterPassword() checks the pr_WindowPtr of your process to find the
  362.     screen to put the requester on (if screen == NULL).
  363.  
  364.   BUGS
  365.     none known
  366.  
  367.   SEE ALSO
  368.  
  369. powerpacker.library/ppErrorMessage         powerpacker.library/ppErrorMessage
  370.  
  371.   NAME  ppErrorMessage()  (V35)
  372.  
  373.     message = ppErrorMessage (errorcode);
  374.  
  375.     char *ppErrorMessage (ULONG);
  376.     D0                    D0
  377.  
  378.   DESCRIPTION
  379.     Returns a pointer to a null-terminated string holding a descriptive
  380.     error message for the supplied error code.
  381.  
  382.     Currently only works for error codes returned by ppLoadData().
  383.  
  384.   INPUTS
  385.     errorcode - error code returned by ppLoadData().
  386.  
  387.   RESULT
  388.     message - pointer to error message (null terminated string) associated
  389.               with error code.
  390.  
  391.   BUGS
  392.     none known
  393.  
  394.   SEE ALSO
  395.     ppLoadData()
  396.  
  397. powerpacker.library/ppFreeCrunchInfo     powerpacker.library/ppFreeCrunchInfo
  398.  
  399.   NAME  ppFreeCrunchInfo()  (V35)
  400.  
  401.     ppFreeCrunchInfo (crunchinfo);
  402.  
  403.     void ppFreeCrunchInfo (APTR);
  404.                            A0
  405.  
  406.   DESCRIPTION
  407.     Free all memory associated with the private crunchinfo structure
  408.     returned by ppAllocCrunchInfo().
  409.  
  410.   INPUTS
  411.     crunchinfo - pointer to private crunchinfo structure.
  412.  
  413.   RESULT
  414.     none
  415.  
  416.   NOTE
  417.     crunchinfo may be NULL, no action will be taken.
  418.  
  419.   BUGS
  420.     none known
  421.  
  422.   SEE ALSO
  423.     ppAllocCrunchInfo(), ppCrunchBuffer()
  424.  
  425. powerpacker.library/ppGetPassword           powerpacker.library/ppGetPassword
  426.  
  427.   NAME  ppGetPassword()
  428.  
  429.     bool = ppGetPassword (screen, buffer, maxlen, checksum);
  430.  
  431.     BOOL ppGetPassword (struct Screen *, UBYTE *, ULONG, ULONG);
  432.     D0                  A0               A1       D0     D1:16
  433.  
  434.   DESCRIPTION
  435.     reqtools.library _MUST_ be available!
  436.  
  437.     Opens a small requester to prompt the user for a password. Returns when
  438.     the user enters a password with a checksum equal to 'checksum' or when
  439.     he has failed to enter a correct password (three chances). The password
  440.     will not be visible when typed.
  441.  
  442.   INPUTS
  443.     screen   - screen where the requester should appear.
  444.     buffer   - buffer to hold correct password. Must at least 17 bytes big!
  445.     maxlen   - maximum length of password, should always be 16.
  446.     checksum - checksum of password we are looking for.
  447.  
  448.   RESULT
  449.     bool - TRUE when the correct password was entered (can be found in
  450.            buffer), FALSE when no correct password was given after three
  451.            attempts.
  452.  
  453.   NOTE
  454.     New for V35: The contents of the buffer will NOT change if the requester
  455.                  is aborted.
  456.  
  457.     This function will be used by ppLoadData() to prompt for a password when
  458.     you called it with 'func' equal to NULL.
  459.  
  460.     Automatically adjusts the requester to the screen's font.
  461.  
  462.     ppGetPassword() checks the pr_WindowPtr of your process to find the
  463.     screen to put the requester on (if screen == NULL).
  464.  
  465.   BUGS
  466.     none known
  467.  
  468.   SEE ALSO
  469.     ppLoadData()
  470.     ppDecrunchBuffer()
  471.  
  472. powerpacker.library/ppLoadData                 powerpacker.library/ppLoadData
  473.  
  474.   NAME  ppLoadData()
  475.  
  476.     error = ppLoadData (filename, col, memtype, &buffer, &len, func);
  477.  
  478.     ULONG ppLoadData (char *, ULONG, ULONG, UBYTE **, ULONG *, BOOL (*)());
  479.     D0                A0      D0     D1     A1        A2       A3
  480.  
  481.   DESCRIPTION
  482.     This function loads a file in memory. The memory necessary to load the
  483.     file will be allocated by this function. Files crunched with PowerPacker
  484.     will be decrunched, plain files will simply be loaded. If the file can't
  485.     be opened ".pp" will be appended before trying again. The address of the
  486.     loaded file will be stored in 'buffer', the length in 'len'. You must
  487.     free this memory yourself (see NOTE) !
  488.  
  489.     The 'func' argument is the address of a function to be called when
  490.     ppLoadData() needs a password to decrypt an encrypted file. If you do
  491.     not want to load encrypted files call with func equal to -1, if you want
  492.     ppLoadData() to use ppGetPassword(), call with func equal to NULL.
  493.  
  494.     If you wish to use your own password prompting function you must call
  495.     ppLoadData() with func equal to the address of this type of function:
  496.  
  497.         BOOL __stdargs myFunction (UBYTE *password, ULONG checksum);
  498.  
  499.     On entry 'password' points to a buffer to hold up to 16 characters and a
  500.     terminating zero (so 17 bytes in all), 'checksum' is the checksum of the
  501.     password we are looking for. Your function must prompt for a string and
  502.     compare the checksum with 'checksum' (use ppCalcChecksum() for this). If
  503.     they are equal you must store the string in 'password' (in C you can use
  504.     'strcpy') and return TRUE, if not you should give the user a few more
  505.     chances (usually three in all) and return FALSE if no correct password
  506.     was entered.
  507.  
  508.     The two arguments are pushed on the stack according to C convention, so
  509.     if you write your function in assembly you will find the arguments on the
  510.     stack, the pointer to the buffer at 4(a7) and the checksum at 8(a7)
  511.     (longwords!). Assembly functions must preserve all registers !
  512.  
  513.     SAS/C users shouldn't forget __saveds if they compiled their program with
  514.     the small data model and wish to use global data in their function.
  515.  
  516.   INPUTS
  517.     filename - pointer to a null terminated pathname of the file to load.
  518.     col      - the effect to be used during decrunching. One of the
  519.                following (defined in "libraries/ppbase.[hi]"):
  520.                    DECR_COL0    - flash color 0
  521.                    DECR_COL1    - flash color 1
  522.                    DECR_POINTER - flash mouse pointer
  523.                    DECR_SCROLL  - weird stuff :-)
  524.                    DECR_NONE    - no decrunching effect
  525.     memtype  - type of memory to allocate (see AllocMem()).
  526.     &buffer  - address of (!) variable to hold memory location of loaded
  527.                file.
  528.     &len     - address of (!) variable to hold length of loaded file.
  529.     func     - function to be called to prompt the user for a password,
  530.                NULL for the the default password prompt and -1 for no
  531.                password prompt.
  532.  
  533.   RESULT
  534.     error - 0 if all went ok, if not one of the following error codes will
  535.             be returned (defined in "libraries/ppbase.(h|i)"):
  536.                 PP_OPENERR   - unable to open file.
  537.                 PP_READERR   - read error.
  538.                 PP_NOMEMORY  - not enough memory to load file.
  539.                 PP_CRYPTED   - file is encrypted (only when 'func' == -1).
  540.                 PP_PASSERR   - incorrect password, 'func()' returned FALSE.
  541.                 PP_EMPTYFILE - file is empty, there is nothing to load.
  542.                 PP_UNKNOWNPP - crunched by unknown version of PowerPacker.
  543.  
  544.   NOTE
  545.     Do not forget to free the memory allocated by this function !
  546.     Use "FreeMem (buffer, len);" before quitting your program, but only if
  547.     ppLoadData() didn't return an error.
  548.  
  549.     After calling 'func()' ppLoadData() doesn't check the checksum again,
  550.     only the returned boolean. Therefore it is VERY important that your
  551.     function is correct and only returns TRUE when the entered password has
  552.     the correct checksum !
  553.     Don't forget to copy your string to the memory pointed to by 'password'
  554.     before leaving 'func()' ! This password is needed to decrypt the file !!
  555.     Note that 'password' is a C string and must be null terminated !
  556.  
  557.     In case you call ppLoadData() with 'func' equal to NULL (use automatic
  558.     password prompting) the pr_WindowPtr of your Process will be used to
  559.     find the screen to open the password requester on. If pr_WindowPtr
  560.     equals 0 or -1 the WorkBench screen will be used, otherwise the screen
  561.     of the pr_WindowPtr window will be used. Only a process can call
  562.     ppLoadData() (it uses DOS) so pr_WindowPtr exists. Set it like this:
  563.  
  564.         struct Window *yourwindow;
  565.         struct Process *proc;
  566.         APTR oldwinptr;
  567.  
  568.         /* Open your screen and window... */
  569.  
  570.         ...
  571.  
  572.         /* set pr_WindowPtr */
  573.         proc = (struct Process *)FindTask (NULL);
  574.         oldwinptr = proc->pr_WindowPtr;
  575.         proc->pr_WindowPtr = (APTR)yourwindow;
  576.  
  577.         ...
  578.  
  579.         /* restore before quitting (VERY IMPORTANT !!) */
  580.         proc->pr_WindowPtr = oldwinptr;
  581.         exit (0);
  582.  
  583.   BUGS
  584.     none known
  585.  
  586.   SEE ALSO
  587.     exec.library/AllocMem(), exec.library/FreeMem(), ppCalcChecksum(),
  588.     ppErrorMessage(), ppGetPassword()
  589.  
  590. powerpacker.library/ppWriteDataHeader   powerpacker.library/ppWriteDataHeader
  591.  
  592.   NAME  ppWriteDataHeader()  (V35)
  593.  
  594.     success = ppWriteDataHeader (lock, efficiency, crypt, checksum);
  595.  
  596.     ULONG ppWriteDataHeader (BPTR, ULONG, BOOL, ULONG);
  597.     D0                       D0    D1     D2    D3:16
  598.  
  599.   DESCRIPTION
  600.     Use this function to write the PowerPacker data header at the
  601.     beginning of a file.
  602.  
  603.   INPUTS
  604.     lock       - BCPL pointer to a DOS file handle.
  605.     efficiency - efficiency used to crunch the buffer.
  606.                  See ppAllocCrunchInfo(). (CRUN_FAST, ... ,CRUN_BEST)
  607.     crypt      - TRUE for a header of an encrypted file, FALSE otherwise.
  608.     checksum   - (if crypt = TRUE) checksum of password used to encrypt.
  609.  
  610.   RESULT
  611.     success - TRUE on success, FALSE if a write error occured.
  612.  
  613.   NOTE
  614.  
  615.   BUGS
  616.     none known
  617.  
  618.   SEE ALSO
  619.     ppAllocCrunchInfo(), ppDecrypt()
  620.  
  621.